home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor1 / ta.doc < prev    next >
Text File  |  1995-03-31  |  8KB  |  243 lines

  1. Author: Pete M. Wilson 
  2.                   README.DOC 
  3.  
  4.     Brief description file for the TA disassembler system. 
  5.  
  6.  
  7. TA is a program the provides an interactive disassembler for the HP 48SX 
  8. ROM.  It is written in Microsoft C and should be fairly portable (I haven't 
  9. tried). 
  10.  
  11. TA uses 5 data files: 
  12.  
  13. HP48MAP.ROM is an ascii listing of the complete ROM contents, produced 
  14.     by downloading all of the ROM to your computer and processing 
  15.     it through the TOROMMAP filter.  This will strip all addresses 
  16.     from the dump file, creating a flat 524,288 byte file. 
  17.  
  18. Two comment files are used by TA. Both have the same format. Each line 
  19. consists of the 5 nibble address being described, followed by a space and the one line comment describing the address. Lines beginning with a '-' are considered deleted. 
  20.  
  21. REMC.MAP is the code comment file. It provides comments explaining what the 
  22.     code at a particular address is doing.  When the corresponding 
  23.     address is UnThreaded or UnAssembled, the comment is appended 
  24.     to the output line. 
  25.  
  26.     For example, the RPL routine at 03188 executes the inner-most code 
  27.     for the DUP routine (i.e. after error checking and setup has been 
  28.     done). It is an assembler routine with an RPL entry point, and 
  29.     UnThreading the entry point yields: 
  30.  
  31.         TA> ut 3188 
  32.             ; *** RPL do DUP *** 
  33.         03188: 0318D ML ENTRY 
  34.         0318D: CF         D=D-1 A               ; room on stack? 
  35.         0318F: 41F        GOC 03181             ; if not,  make some 
  36.         03192: 143        A=DAT1 A              ; get obj @ TOS 
  37.         03195: 1C4        D1=D1- 5              ; push object again 
  38.         03198: 141        DAT1=A A 
  39.         0319B: 142        A=DAT0 A              ; cont RPL 
  40.         0319E: 164        D0=D0+ 5 
  41.  
  42.     The comments following each disassembled line are stored in REMC.MAP. 
  43.  
  44.     NOTE: The disassembler stops after outputting 8 lines - the 
  45.     routine above continues for one more line. 
  46.  
  47.  
  48. REMA.MAP is the address comment file. It provides comments explaining the 
  49.     purpose of address references. For example, the DUP routine is at 
  50.     1FB87.  UnThreading this yields: 
  51.  
  52.         TA> ut 1fb87 
  53.             ; *** XLIB: 10D002 DUP *** 
  54.         1fb87: 02D9D Type 8: RPL Program 
  55.         1fb8c: 18AA5 save Last RPL Token / verify DEPTH >= 1 
  56.         1fb91: 03188 RPL do DUP 
  57.         1fb96: 0312B End RPL Program 
  58.  
  59.     Each comment following the threaded routine address is stored in 
  60.     REMA.MAP.  In addition, the comment line preceding 1FB87 (and in 
  61.     the above example, preceding 03188) is stored in REMA.MAP. 
  62.     As a further example, the RPL routine at 14039 is a very deep internal 
  63.     routine to the code for ERRN.  It pushes the Last Error Number as a 
  64.     short integer or address type. 
  65.  
  66.         TA> ut 14039 
  67.             ; *** Push Last Err# as Short Int *** 
  68.         14039: 1403E ML ENTRY 
  69.         1403E: 34FF607    LCHEX 706FF   ; Save Last Err# 
  70.         14045: 8D3B411    GOVLNG 114B3  ; Push @C.A as new Short Int 
  71.  
  72.             ; *** Push @C.A as new Short Int *** 
  73.         114B3: DA         A=C A 
  74.         114B5: 8FB9760    GOSBVL 0679B  ; Save Regs D, B, D1, D0 (uses C) 
  75.         114BC: 130        D0=A 
  76.         114BF: 142        A=DAT0 A 
  77.         114C2: 8DC7530    GOVLNG 0357C  ; Push A as new Short Int      
  78.  
  79.         The comments after 706FF, 114B3 0679B and 0357C are stored in 
  80.         REMA.MAP and are automatically appended to the disassembly. 
  81.  
  82. REMA.INX and REMC.INC are index files for the .MAP files.  These are binary 
  83.     arrays of Adress, .MAP offset information in sorted order. A binary 
  84.     search on these arrays in core is used to lookup comment information. 
  85.     If the .MAP file is edited using a text editor, the corresponding 
  86.     .INX file must be deleted. The TA program will automatically 
  87.     re-create them correctly. 
  88.  
  89.  
  90.  
  91. A number of features of TA disassembly should be apparent from the examples. 
  92. Here is a listing of some of the more significant features. 
  93.  
  94.     1. Initial disassembly mode is set by the command used to start 
  95.        disassembly. 
  96.  
  97.     2. UnThread to UnAssemble mode switching is handled automatically. 
  98.  
  99.     3. Disassembly/unthreading is stopped automatically when a termination 
  100.        point is reached. 
  101.  
  102.     4. Absolute GOTOs in assembly are followed automatically. 
  103.  
  104.     5. The HP-71 style mnemonics are used. (but see notes at end) 
  105.  
  106.     6. Currently, disassembly is only available for the ROM. Other Binary 
  107.        files cannot be handled (i.e. I'm working on the USAG command). 
  108.  
  109.     7. In-line literal RPL Objects are not handled by the UnThreader. 
  110.  
  111.     8. Only the HP-71 instruction set is currently understood. I don't 
  112.        have access to Alonzo's notes on the 28 or the new instructions 
  113.        in the 48 - if anyone can tell me these, I'd be overjoyed to add 
  114.        them to the program. 
  115.  
  116.  
  117.                SHORT COMMAND REFERENCE 
  118.  
  119. UT    UnThread 
  120.  
  121.     UT addr 
  122.  
  123.     Example: UT 3188 
  124.  
  125.     The UnThread command begins disassembly in UnThread mode at a given 
  126.     address. Up to 8 lines of mixed RPL/assembly output will be produced. 
  127.     If an RPL end program is encountered, output will stop. If RPL CODE or 
  128.     ML Entry is encountered, disassembly mode will be switched to 
  129.     UnAssemble automatically. 
  130.  
  131. UA    UnAssemble 
  132.  
  133.     UA addr 
  134.  
  135.     Example: UA 114B3 
  136.  
  137.     The UnAssemble command begins disassembly in UnAssemble mode at a 
  138.     given address. Up to 8 lines of assembly will be produced. If an 
  139.     Unconditional Return or an indirect Goto (i.e. PC=(A)) is encounterd, 
  140.     disassembly will be stopped. If an unconditional Goto is encountered, 
  141.     it will be followed. 
  142.  
  143. U    Un-continue 
  144.  
  145.     U 
  146.  
  147.     The Unassemble command continues at the last unassembled address, in 
  148.     the last used mode, for another 8 lines or until a stop condition is 
  149.     reached. 
  150.  
  151. CA    Comment Address 
  152.  
  153.     CA addr text 
  154.  
  155.     Example: CA 114b3 Push @C.A as new Short Int 
  156.  
  157.     The Comment Address command creates a new comment on an address. Any 
  158.     reference to the address will automatically have the comment appended 
  159.     to the line. Any existing address comment for the address is replaced. 
  160.  
  161. CC    Comment Code 
  162.  
  163.     CC addr text 
  164.  
  165.     Example: CC 318d room on stack? 
  166.  
  167.     The Comment Code command creates a new comment on the code at an 
  168.     address. Any disassembly of the address will have the comment 
  169.     appended to it. Any existing code comment for the address is replaced. 
  170.  
  171. CCD    Comment Code Delete 
  172.  
  173.     CCD addr 
  174.  
  175.     Example: CCD 318d 
  176.  
  177.     The Comment Code Delete command removes a code comment for an address. 
  178.  
  179. CAD    Comment Address Delete 
  180.  
  181.     CAD addr 
  182.  
  183.     Example: CAD 114b3 
  184.  
  185.     The Comment Address Delete command removes an address comment for an 
  186.     address. 
  187.  
  188. D    Dump 
  189.  
  190.     D addr 
  191.  
  192.     Example: D 71AD8 
  193.  
  194.         TA> d 71ad8 
  195.         71ad8: E06556273796F6E6 0284054383D22411  .Version  HP48-B. 
  196.         71af8: 34F6079727967686 4702840502139383  Copyrigh t HP 198 
  197.  
  198.     The Dump nibbles command outputs the nibbles at a particular ROM 
  199.     address in Hex and ASCII format. It produces 8 lines of output. 
  200.  
  201. Q    Quit 
  202.  
  203.     Q 
  204.  
  205.     The Quit command exits TA.  If any .INX files have been changed or 
  206.     were missing, they are written out automatically. 
  207.  
  208.  
  209.  
  210. Future Enhancements 
  211.  
  212. These are some things I'm hoping to add to the program.  Please feel free to 
  213. make suggestions. 
  214.  
  215. A utility program to merge REMC/REMA files from different people. 
  216.  
  217. Automatic recovery of space in REMC/REMA. 
  218.  
  219. Complete instruction set support (if someone will tell me what the new 
  220. instructions are). 
  221.  
  222. A switch to support Alonzo's mnemonics (if I find out what they are). 
  223.  
  224. A type file that marks the type of code at addresses so RPL/Assembly mode 
  225. is known for some addresses (i.e. for U addr). 
  226.  
  227. The ability to work with Binary (or ASCII translated) 48 program files, with 
  228. separate comment files for these and automatic connection to the ROM MAP. 
  229.  
  230. A type file for data area so the Dump command can be told the format of ROM 
  231. Data Tables (i.e. the command area, the version string, ...). 
  232.  
  233. A notes system to record questions and comments that will store speculations 
  234. on code purposes before its been completely understood. 
  235.  
  236. An address stack to allow following RPL calls and returns and assembly gosubs. 
  237.  
  238.  
  239.                     Pete M. Wilson 
  240.                     07/14/90 
  241.  
  242.                     on HP BBS as wilsonpm 
  243.